/**
 * File Cache.java
 * ---------------------------------------------------------
 *
 * Copyright (C) 2012 David Bauske (david.bauske@googlemail.com)
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 *
 * - The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 * - The origin of the software must not be misrepresented.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 *
 * TL;DR: As long as you clearly give me credit for this Software, you are free to use as you like, even in commercial software, but don't blame me
 * 		if it breaks something.
 */
package net.cl.util.collections;

/**
 * Cache interface. Implementing classes support caching values for given
 * argument objects. This way it is ensured that the possibly lengthy operation
 * of computing values is not executed if it already was previously.
 *
 * @param A The type of the argument passed to the computing method.
 * @param R The return type of the computation
 *
 * @author David
 */
public interface Cache<A, R>
{
	/**
	 * Gets the computed value for the given argument. If this value wasn't computed yet,
	 * computation is initiated, the result is cached and returned.
	 *
	 * @param argument The argument to get the return value for.
	 * @return The computed value for the given argument.
	 * @throws InterruptedException if the thread is interrupted during computation.
	 */
	public R get(A argument) throws InterruptedException;

	/**
	 * Erases any previously computed value for the given argument, forcing a recomputation
	 * on the next request.
	 *
	 * @param argument The argument object to invalidate the value of. If the value of the
	 * 		argument wasn't computed yet, nothing happens.
	 */
	public void invalidate(A argument);

	/**
	 * Removes all cached values from the cache.
	 */
	void invalidateAll();
}